---
title: 查找替换
icon: TextSearch
---

<MetaData
  lang="zh-CN"
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-find-replace',
      locale: '@univerjs/preset-sheets-find-replace/locales/zh-CN',
      style: '@univerjs/preset-sheets-find-replace/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs/find-replace',
      locale: '@univerjs/find-replace/locale/zh-CN',
      style: '@univerjs/find-replace/lib/index.css',
    }, {
      client: '@univerjs/sheets-find-replace',
      facade: '@univerjs/sheets-find-replace/facade',
      locale: '@univerjs/sheets-find-replace/locale/zh-CN',
    }],
    server: '否',
  }}
/>

查找替换功能允许用户在电子表格中快速查找特定内容并进行替换，支持多种匹配方式和选项，帮助用户高效处理数据。

<PlaygroundFrame lang="zh-CN" slug="sheets/find-replace" clickToShow />

## 预设模式

### 安装

```package-install
npm install @univerjs/preset-sheets-find-replace
```

### 使用

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsFindReplacePreset } from '@univerjs/preset-sheets-find-replace' // [!code ++]
import UniverPresetSheetsFindReplaceZhCN from '@univerjs/preset-sheets-find-replace/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-find-replace/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsFindReplaceZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsFindReplacePreset(), // [!code ++]
  ],
})
```

## 插件模式

### 安装

```package-install
npm install @univerjs/find-replace @univerjs/sheets-find-replace
```

### 使用

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverFindReplacePlugin } from '@univerjs/find-replace' // [!code ++]
import FindReplaceZhCN from '@univerjs/find-replace/locale/zh-CN' // [!code ++]
import { UniverSheetsFindReplacePlugin } from '@univerjs/sheets-find-replace' // [!code ++]
import SheetsFindReplaceZhCN from '@univerjs/sheets-find-replace/locale/zh-CN' // [!code ++]

import '@univerjs/find-replace/lib/index.css' // [!code ++]

import '@univerjs/sheets-find-replace/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      FindReplaceZhCN, // [!code ++]
      SheetsFindReplaceZhCN, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverFindReplacePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsFindReplacePlugin) // [!code ++]
```

## Facade API

完整 Facade API 类型定义，请查看 [FacadeAPI](https://reference.univer.ai/zh-CN)

### 创建文本查找器

`univerAPI.createTextFinderAsync()` 创建一个文本查找器，返回一个 `FTextFinder` 实例。

以下是 [`FTextFinder`](https://reference.univer.ai/zh-CN/classes/FTextFinder) 上的一些成员方法：

| 方法 | 描述 |
| ---- | ---- |
| findAll | 获取当前表格中所有匹配的单元格，当前匹配的单元格是最后一个匹配的单元格 |
| findNext | 获取当前表格中下一个匹配的单元格，如果存在则返回下一个匹配的单元格，并将当前匹配的单元格移动到下一个匹配的单元格 |
| findPrevious | 获取当前表格中上一个匹配的单元格，如果存在则返回上一个匹配的单元格，并将当前匹配的单元格移动到上一个匹配的单元格 |
| getCurrentMatch | 获取当前表格中当前匹配的单元格 |
| matchCaseAsync | 设置匹配大小写选项，如果为 true，则查找操作将匹配大小写，否则查找操作将忽略大小写 |
| matchEntireCellAsync | 设置匹配整个单元格选项，如果为 true，则查找操作将匹配整个单元格的值，否则查找操作将匹配单元格值的一部分 |
| matchFormulaTextAsync | 设置匹配公式文本选项，如果为 true，则查找操作将匹配公式文本，否则查找操作将匹配值 |
| replaceAllWithAsync | 替换所有匹配的文本为给定文本 |
| replaceWithAsync | 替换当前匹配的文本为给定文本 |
| ensureCompleteAsync | 确保查找操作已完成。特别是当当前表格更改时，请使用此方法确保查找操作已完成 |

```typescript
// 假设当前表格是空表
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 设置一些值到 A1:D10 范围内
const fRange = fWorksheet.getRange('A1:D10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// 创建一个查找文本 '5' 的查找器
const textFinder = await univerAPI.createTextFinderAsync('5')

// 找到所有包含文本 '5' 的单元格
const matchCells = textFinder.findAll()
matchCells.forEach((cell) => {
  cell.getA1Notation() // D2, C3, B4, A5
})
```
